Faults

Detailed description of API:

Version & Updates

View Previous Revisions

Version	Revision Date	Revision History
1.0	August 2022	New Release
1.1	October 2022	Included the Staging / QA / UAT instance URL and revised the Request and Response Parameters
1.2	November 2022	Updated URLs for Dev and UAT
1.3	28th Nov 2022	Update APIM URL to given domain URL
1.4	31st Aug 2023	Updated the Prod URLs, Pictorial representation of the data flow, Pre-requisites to access the API, Response Codes. Moved Authentication Section to API and Connection Details, Sample Request and Response files to Sample Request and Responses section. Renamed Connection Details to API and Connection Details Corrected Navigation Headings
1.5	8th Sep 2023	Updated description in ‘Overview’ section, API Request parameter types in ‘API Request Description section and added API, Request types.
1.6	16th Oct 2023	Project title change
1.7	24th Oct 2023	Updated section 5.1.2. API Response Description / Structure
1.8	25th Jun 2025	Added Request type

Version	Revision Date	Revision History
1.9	30th Jul 2025	Added NAFTA endpoint details

Overview

Faults API exposes vehicle fault data to the DMS providers, enabling them to have all the relevant fault information about the equipment required for a work/reapir order of vehicle.

A DMS provider can query the active fault and/or the historical (30 days) fault data on a real time basis by providing the Vehicle Identification Number (VIN) and/or start and end dates via API request parameter. The API provides geographical information of the equipment and the various faults occurred between the requested dates as a response.

The data of vehicles with this status will not be shared with user:

• Not connected ​
• Never activated on legacy​
• Never activated​
• Monitoring ​
• Expired ​
• Back to monitoring

Please refer to diagram below for information on the data flow of this interface.

Pre-requisites

Pre-requisites

• Dealer must use their Dealer Portal credentials to authorize API call
• Each DMS provider will have a Subscription key assigned by CNHi team, please reach out to dlnadmssupport@cnh.com for assistance
• Each Subscription key is unique to DMS and the environment it belongs to

Authentication

Authentication

• DMS will pass Basic auth in HTTP header with username/password
• Each DMS provider will have a subscription_key assigned by CNHi team, please reach out to dlnadmssupport@cnh.com for assistance
• The UserID and Password will be set up in the Dealer Portal by the Dealer uniquely for DMS access to interfaces
• DEP API will require subscription_key in HTTP header to identify client

API Format

CNHi has built a data exchange platform, which provides the flexibility to the end users to request information from CNHi system in the following format.

• REST

The DEP takes care of the format transformations (as needed) to process the request and provide a response to the DMS system. REST format is always suggested for greater simplicity.

Connection Details

Endpoints

Environment	API URL	API	Request Type
UAT / Staging	https://{base_url}/external/services/v1/assets/{assetid}/faults/{startdate}/{enddate}	REST	GET
Production	https://{base_url}/external/services/v1/assets/{assetid}/faults/{startdate}/{enddate}	REST	GET

Request Description

Name	Type	Is Required	Default Value	Comments
assetid	String	True	--	Serial/Vehicle Identification number of the equipment
startDate	Date Time	True	--	The date- time notation as defined by RFC 3339, section 5.6, ex: 2017-07-21T17:32:28Z
endDate	Date Time	True	--	The date- time notation as defined by RFC 3339, section 5.6, ex: 2017-07-21T17:32:28Z

Response Description

Location

Name	Type	Description
time	string (date- time)	The date-time notation as defined by RFC 3339, section 5.6, for example, 2017-07-21T17:32:28Z.
pos.time	date-time	Datetime from GPS. The date-time notation as defined by RFC 3339, section 5.6, for example, 2017-07-21T17:32:28Z.
pos.lat	double	Latitude, GPS data. From pos_point Point object.
pos.lon	double	Longitude, GPS data. From pos_point Point object.
country.code	string	Denoting geographical location of vehicle code
country.name	string	Decoded value of country.code
country.timeZone	string	Timezone of local location of vehicle
records	array[fault]	Fault records

Fault

Name	Type	Description
eventType	String	MEDIUM_TRACTOR_FAULT_TELEMATIC_DIAG, HARVESTER_FAULT.
Dtc	Integer	Diagnostic Trouble Code.
Spn	integer	Suspect Parameter Number.
Fmi	integer	Failure Mode Identifier.
sourceAddress	integer	Source address or electronic control unit.
Description	String	Enriched DTC description.
Source	String	Fault source, either Vehicle bus or ISO bus (only Vehicle bus for now).
applicationDesacription	String	DTC application specific description.
Application	String	Application name (platform)
Standard	String	Automotive engineers standard.
System	String	System
systemDescription	String	System Description
cnhEcu	String	CNH ECU
originEcu	String	Originating ECU
originEcuDescription	String	Originating ECU description
yellowWarnlamp	Boolean
redStopLamp	Boolean
specLamplcon	Boolean
priorityOnBoard	Integer
priorityOffBoard	Integer
rawPriority	Integer	Raw priority
visibleCustomerOffBoardDealer	Boolean	Visible to the customer (off board dealer).
visibleCustomerOffBoardDealerRelayedRecords	Boolean	Visible to the customer (off-board dealer) relayed records. If experimental=true the property is fetched from faults_x and faults_x_v2 tables. If experimental=false the property is fetched from faults_x and faults_x_v2 table.
visibleCustomerOffBoardGrower	Boolean	Visible to the customer (off board grower).
visibleCustomerOffBoardGrowerRelayedRecords	Boolean	Visible to the customer (off board grower) relayed records.
visibleCustomerOnBoard	Boolean	Visible to the customer (on board).
occurrences	Integer	A counter that counts the occurrence of the error condition for each SPN/FMI or DTC.
syntheticOccurrences	Long	A synthetic counter that counts the occurrence of the error condition. Unlike occurrences this value doesn't come from the device but is calculated during Faults processing and is reset every month. See Alarms and Faults P-rocessing for more details.
Active	Boolean	Status; If experimental == false then faults.fault_status ! = 0 else faults.fault_active .
Enriched	Boolean	Enriched; Whether a description and other fields were enriched with the DTC catalog.
engHours	Double	The last known value of ENG_HOURS metric within configured metricLateness duration from the Fault time. For example, the most recent value of ENG_HOURS metric has event_timestamp between faults.event_timestamp - metric Lateness (not included) and faults.event_timestamp (included). Right now, metricLateness = 15 minutes.
rawDescription	String	Description field from a raw message.
errorTags	Array [String]	The list of processing warnings separated by a comma. If an array is empty, then error Tags will not be shown in response.
relayingMethod	String	Relaying method.
relayedAddress1	Integer	Relayed Source Address 1.
relayedAddress2	Integer	Relayed Source Address 2.
relayedEcu1	String	Relayed Ecu1
relayedEcu2	String	Relayed Ecu2
relayedSpn	Integer	Relayed SPN.
relayedFmi	Integer	Relayed FMI.
relayedCode	Long	Relayed DTC code.
masterStandard	String	Master standard.
masterSourceAddress	Integer	Master Source Address.
masterSpn	Integer	Master SPN.
masterFmi	Integer	Master FMI.
masterDtc	Integer	Master DTC code.
localizedDescription	String	The unifiedDescriptionLocalization field from Localization API response for the corresponding Fault.
activationTimestamp	String (date time)	Time when the Fault first activated.

Sample Response

Download Sample Response

Response Codes

Status Code	Message	Reason
200	API request success	Succesful connection to API and backend
500	Internal Server Error	Unsuccessful conection to API or backend
401	Access denied due to invalid credentials!	Bad credentials, check username and password
404	The requested VIN is not a connected vehicle, please check the VIN.	Vehicle does not have modem or telematic equipment.
404	VIN is not available, please check the VIN.	Incorrect VIN input.
404	No data found, Telematic subscription has expired for this VIN.	Telematic subscription for the VIN has expired.
404	Vehicle data currently not available due to Telematic connectivity issue.	Vehicle is unable to connect/transmit telematic data.
404	The requested VIN is inactive or has never been activated, please check Telematic subscription.	Telematic subscription is either inactive or not activated.
404	The requested VIN or Telematic data could not be found but may be available in the future, please check the VIN and Telematic subscription.	Service is down and/or trouble with backend.